ASP Advantage 1994 2nd Q2

home *** CD-ROM | disk | FTP | other *** search

/ ASP Advantage 1994 2nd Q2 / The Association of Shareware Professionals - The Official ASP Advantage (2nd Quarter)(1994).bin / files / progming / peo / manual.doc < prev next >

Wrap

Text File | 1994-02-10 | 59.4 KB | 1,299 lines

JAMES W. YOUNG & ASSOCIATES, INC. 1403 5th Street, Suite G Davis, California 95616 (916)756-3051 Dear Professional: Thank you for taking a look at James W. Young & Associates, Inc.'s COBOL system analysis tool, Program Entity Organizer (PEO). This is the same version of PEO we use to provide top notch services and support for our clients. TERMINOLOGY PEO refers to the screens which the user works with to analyze the COBOL programs. However, in general, PEO refers to the entire system; i.e., the batch programs (the supporting software) and the screens. SEO refers to the batch portion of PEO. SEO is the supporting software for PEO. SEO consists of a preprocessor and a parser. MACHY refers to the group of senior programmer/analysts that developed the PEO and SEO software. It is also the name of the main directory that is created at installation. Application identifier is an important part of PEO. It represents a particular group of COBOL programs and their copybooks. Each application identifier (i.e., a unique set of COBOL programs and copybooks) must be created as a subdirectory of MACHY. The actual source code does not have to be in the subdirectory. The first application identifier subdirectory is created at install time. Publisher refers to James W. Young & Associates. Author refers to the copyright holders for the PEO and SEO software. WHAT IS PEO? PEO is a COBOL source code analysis and documentation tool. It replaces the compiler output as the primary analysis tool. It gives you a huge leap in productivity and confidence; productivity, because PEO handles the cross reference grunt work and bundles main programs and all their subprograms into a single package for analysis; confidence, because you can be sure you've covered everything! Anything you can do with a compile listing you can do many times faster with PEO and with virtual one-hundred percent accuracy. You can identify and document business functions in a fraction of the time formerly required. You can identify and document program control functions in a fraction of the time formerly required. PEO is a custom tool used by James W. Young & Associates and clients for more than two years. It was designed and developed by four senior programmer analysts with over 90 years combined experience with mainframe COBOL systems. It's designed for the real world of esoteric (spaghetti) code; numerous modifications; numerous subprograms; alternate entry points; a plethora of GO TO's, ALTER's; superfluous group moves and group parameters; AND modern, structured code. THE PEO DEMONSTRATION PEODEMO is a very tiny COBOL program with no function other than demonstrate the look and feel of PEO; and, to show you some of the features of PEO. Don't let the small size of the demo fool you; there's no size limit on programs as long as you have the DASD. Copy the demonstration and peo.exe files to a hard drive to get an accurate idea of the speed of PEO. Change to the drive and directory containing peo.exe and the PEODEMO.* files. You MUST do this to run the demonstration. Select PEODEMO from the first screen. The PEODEMO.HIH file is output from the parser and shows the call hierarchy, alternate entry points, and source files containing the entry point (if different from the entry name). The PEODEMO.DTE file is an example of a data element name filter. The string "YYMM" was the filter. The file contains the selected names which met the criterion. These names can be used with the PEO screens to analyze their use in the COBOL system. You may specify multiple filters. DISCLAIMER - AGREEMENT USERS OF PROGRAM ENTITY ORGANIZER (PEO) AND ITS SUPPORTING SOFTWARE, THROUGHOUT THIS DOCUMENT, REFERRED TO AS SEO, MUST ACCEPT THIS DISCLAIMER OF WARRANTY: PROGRAM ENTITY ORGANIZER (PEO) AND SEO ARE SUPPLIED AS IS. THE AUTHOR AND PUBLISHER DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THE WARRANTIES OF MERCHANTABILITY AND OF FITNESS FOR ANY PURPOSE. THE AUTHOR AND PUBLISHER ASSUME NO LIABILITY FOR DAMAGES, DIRECT OR CONSEQUENTIAL, WHICH MAY RESULT FROM THE USE OF PROGRAM ENTITY ORGANIZER (PEO) AND SEO. THE USER MUST ASSUME THE ENTIRE RISK OF USING THE PROGRAM. ANY LIABILITY OF THE AUTHOR AND PUBLISHER WILL BE LIMITED EXCLUSIVELY TO PRODUCT REPLACEMENT OR REFUND OF PURCHASE PRICE. CONTENTS: I. Some Information About Getting Started II. The Outline of the User's Manual III. Draft Copy of the User's Manual. IV. JWY&Assoc., Inc.'s support for PEO. V. qikstart I. Some Information About Getting Started Here is some information which should get you started without having to look at very much of the User's Manual. The install information is at the very end of this file. PEO is as easy to use as 1, 2, 3: 1. preprocess all the COBOL source code in the directory, 2. parse the program(s) and load into the PEO data base, and 3. analyze the program. Step one must be done at least one time during the "life-cycle" of PEO for a particular set of COBOL programs. You repeat step one only when a program is added to the directory or when program names or alternate entry point names have been added or changed; or, internal/external file definition names have been added or changed. Step two depends upon step one being run at least one time. Step two must be done when you choose a program for analysis for the first time. Usually, you will not have to do step two more than once for each project. The capabilities PEO gives you make it possible to do a thorough analysis, make the changes to the program, and forget about the program until the next project. Step three depends upon step two before a program can be analyzed. Step three is repeated as often as necessary to analyze the program(s). All three steps depend upon a certain configuration of DOS directories. The main working directory is created at install time. It is named, MACHY. The preprocessor and parser are copied to this directory by install.bat. A particular set of COBOL source code (referred to here as an application or application ID) must be given a name by the user. The application ID is used to create a subdirectory of MACHY. The application ID is a required command line parameter when you run install.bat. The third directory required by PEO is named EXS and is created by install.bat as a subdirectory of application ID. The PEO.exe file is copied to the EXS subdirectory by install.bat. Here is a representation of the DOS directories: root the c: drive | MACHY the preprocessor and parser are here | application ID the working directory for a set of COBOL | code | EXS the peo screens (peo.exe) reside here The install.bat file also creates a COBOL and a COPY sub directory of application ID. These are the default directories for the COBOL source code. You can copy the COBOL programs and copybooks to these directories, respectively. Otherwise, you must use the SEOCOBOL and SEOCOPY DOS environment variables to point the preprocessor and parser to the COBOL source code. (Notice, that is SEO..., not PEO.... The preprocessor and parser are referred to as SEO.) SEO does require .cbl and .cpy file extensions for your COBOL programs and copybooks, respectively. Please see "Naming conventions for your source code" in the User's Manual. All three steps depend upon the DOS command line to be executed. (step three is an exception, see next paragraph.) The first two steps depend upon command line parameters. Step three, PEO, does not require any command line parameters. You will be asked by the first PEO screen to provide the information PEO needs. The first two steps are batch jobs and should be run from the DOS command line only. PEO is not a batch job and can run under Microsoft's Windows (R) or similar product; we have not, however, run PEO under any system other than DOS and Windows. To run the first two steps you must always provide the application ID as the first command line parameter. The application ID is the only parameter for step one, the preprocessor. Step two, the parser, requires the application ID and the main program name(s), i.e., the file name(s) in the COBOL directory, with or without the file name extension. If you omit the main program name(s), the parser will process all the COBOL programs in the directory. You do not have to provide the names of any subprograms; that is the job of the preprocessor. You can parse "main" programs only. The parser will include all subprograms automatically based upon the latest information supplied by the preprocessor. All three steps correspond to executable files: prepro seoexp00 peo. Step one is prepro.bat which executes the two preprocessor programs, seopre00.exe and seopsu00.exe. The application ID is a required command line parameter. Step two is seoexp00.exe (the parser). The application ID is a required command line parameter. It must be the first parameter. The second parameter is the file name of the main program to be parsed. If you run seoexp00.exe with only the application ID, it will parse all the programs in the COBOL directory. The third, fourth, etc. parameters are file names of other main programs to be included (along with all their subprograms) in a single analysis package; seoexp00.exe will ask you to type in a one to eight byte name for the analysis package if you type more than one program name on the command line. The name you type in is the name you provide step three (peo.exe) to load into the PEO data bases; otherwise, if there is only one main program you provide step three with the program name. Step three is peo.exe (the user interface). The first screen you see will ask you to choose to view a program which already exists in the PEO data bases or to choose to load a new program. If you choose to load a new version of an existing program, you will be asked to permit PEO to overlay the old version.The name you provide to PEO is the main COBOL program name; or, if you combined programs into one analysis package, it's the name you typed into step two, seoexp00.exe. The first two steps, the batch preprocessor and parser, produce a *.seo file. You should check these for such things as missing copybooks, missing subprograms, unknown data element names, and unknown procedure names. Other messages are information which may indicate the parser failed to recognize something because of an unusual condition; e.g., a missing period separator. More arcane messages are rare and would require product support. The preprocessor *.seo file is named SEOPREP.SEO and is in the application ID subdirectory. The parser *.SEO file is named by the COBOL program's name with a .SEO extension. This file is in the EXS subdirectory of the application ID. All three steps have screens. The two batch steps, steps one and two, will show the first few lines of the program being processed and the identity of the main program, subprogram, and copybook currently being processed. In addition, the running line count is displayed. PEO's screens are described in the User's Manual. If you've installed the SEO and PEO files and read through the above, you're ready to put PEO to work. The instructions for installing the software are at the very end of this file. Here's how it works. It's likely your COBOL source code is already installed in a directory; or, you do not want to put the programs and copybooks in a PEO directory. If either is true, type in set SEOCOBOL=drive[path] set SEOCOPY=drive[path] where drive is the letter of the drive containing the COBOL source code and [path] is the path to the directory of the source code. If you did put the COBOL programs into the COBOL subdirectory of application ID and you put the copybooks in the COPY subdirectory of the application ID, you will not have to set the environment variables (SEOCOBOL and SEOCOPY). If you did one and not the other, use the appropriate environment variable. Before you proceed, check the information in the User's Manual ("Naming conventions for your source code"). The COBOL programs must have a .cbl file extension and the copy books must have a .cpy file extension. Next, you're ready to run the preprocessor. Remember, you will not have to run the preprocessor every time. Please refer to the description of the preprocessor above and in the User's Manual. You run the preprocessor by typing in: prepro applid where prepro in the batch file which executes the two preprocessor programs and applid is the application ID. It should take about fifteen minutes for each 100,000 lines of code in the COBOL program and copybook directories. After the preprocessor is finished, check the seoprep.seo file in the application ID directory. It will tell you if any copybooks are missing. Now, run the parser. In this example there will be only one main program to parse. You parse the program by typing in seoexp00 applid mainprogramid where seoexp00 is the parser, applid is the application ID, and mainprogramid is the file name (with or without the file extension) of the main program. How long will the parser take? It depends upon the size of the program and how the program is coded. Another factor is a RAM drive, see "PERFORMANCE CONSIDERATIONS" in the User's Manual. Obviously, a large program is going to take longer than a small program. The parser works at about a thousand lines per minute. But, a COBOL program with a lot of group-level activity; e.g., group MOVE's and group parameters, can take a longer than a program of similar size but little group-level activity. Before loading the program into PEO, check the *.seo file produced by the parser. It is named by using the main program name and a .seo extension. The file will be in the EXS sub directory of applid. The main things to look for are missing files; e.g., copybooks and subprograms. Messages like, UNKNOWN DATA ELEMENT, are also important. If all the parts for the program were there, the file will contain only the header record. Now load the program into the PEO data bases. This is done by invoking PEO. If you did not put PEO (peo.exe) into Windows (R), PEO can be executed by switching to the EXS subdirectory of applid and typing in peo The first screen you see will let you load the COBOL program into the PEO data bases. Once the program is loaded, you will see the program's name in PEO's window of program names. Please see "USING THE PEO SCREENS" in the User's Manual; or, just go ahead and do it. You'll find the process to load the COBOL into the PEO data bases very easy and, when PEO is done, you can go right into the analysis screens. You'll find the analysis screens fairly intuitive. One final note. PEO was designed for mainframe COBOL; e.g., ANS74, ANS85, OS/VS, and COBOL II. It does not support many of the extensions found in PC-based COBOL. See the file CAUTION.DOC. JAMES W. YOUNG & ASSOCIATES, INC. 1403 5th Street, Suite G Davis, California 95616 (916)756-3051 II. The Outline of the User's Manual HARDWARE AND SOFTWARE REQUIREMENTS GETTING STARTED Tools required. Installing PEO. What the install process does. INSTALLING THE COBOL SOURCE CODE Naming conventions for your source code. Paths to your source code. Adding new source code (after installation). Clean compiles only, please. PREPARING DATA FOR PEO. The preprocessor Main Programs The SEOPREP.SEO file The <progid>.seo file Loading output from the parser into PEO. USING THE PEO SCREENS No training required. The PEO Screens. The PEO Data Element Selection Screen The PEO Source Display Screen. The PEO Element Display Screen The target element and affected elements Picking a target Linking CALL and ENTRY PT relations. The PEO Multiple Element Selection Screen CAUTIONS. ADDITIONAL INFORMATION TYPE RELATIONS CODES PERFORMANCE CONSIDERATIONS RESERVED WORDS III. Draft Copy of the User's Manual. HARDWARE AND SOFTWARE REQUIREMENTS The basic PC platform required to run the preprocessor and parser portions (i.e., SEO) would be a 80386 or 80486 PC with at least 4MB of memory and a substantial hard disk... say 200MB or larger, if you have a large number of COBOL programs. A removable storage medium, such as a Bernoulli Box would make an ideal environment... and a tape backup would be desirable. Once the files have been created by the parser, they may be loaded on any available plat- form that has sufficient disk storage. We have run the screens (PEO) on 8088 and 8086 machines with 640K of memory and 40MB hard disks. In most cases, the preprocessor and the parser run with about 550K of memory; it's only when the number of elements in a record exceed approximately 2300 that the parser runs out of memory. Using DOS 5.0 or higher is desirable because most system programs can be loaded into high memory leaving well over 600,000 bytes available for applications like the parser, SEO. PEO and SEO both run under DOS. PEO is very well behaved under Windows, as a DOS application; in fact, we recommend running PEO under Windows. The preprocessor and parser (SEO) are both batch jobs which should not be run under Windows. GETTING STARTED Tools required. It does require some tools (knowledge of DOS commands) to install and use PEO and SEO. Specifically, you should under- stand the basic DOS concepts of directories, "paths", command line parameters, file names, and extensions. You may need to know how to use the RENAME, MD, and SET commands. Installing PEO. Please refer to "How to install" at the end of this readme.doc file. What the install process does. The install process creates a subdirectory of the hard drive. The subdirectory is named, MACHY. The SEO software is copied to the MACHY directory. The install process then creates a sub directory for the application identifier. This is a subdirectory of MACHY. Then the install process creates three subdirectories of the application identifier: id COBOL, COPY, and EXS. Here's how it looks root | MACHY |- application identifier |- COBOL |- COPY |- EXS The PEO software (peo.exe) is copied to the EXS subdirectory. The software installation process is now complete. The MACHY directory is the working directory for the SEO software (pre- processor and parser) and EXS is the working (default) directory for peo.exe. INSTALLING THE COBOL SOURCE CODE You must now give access to your COBOL source code to the SEO reprocessor and parser. The "simplest" way is to copy the COBOL source code to the COBOL subdirectory of the application identifier created by the install process. The copybooks must be copied to the COPY subdirectory of the application identifier. However, as you will see in "Paths to your source code", you do not have to use the default directories. Naming conventions for your source code. The SEO preprocessor and parser require a .CBL extension for the COBOL source code and a .CPY extension for the copybooks. You can use the DOS RENAME command to add the extension (or change to the extension). If you are not familiar with the RENAME command, you can add/change extensions for all members of a directory with just one RENAME command. Please refer to the RENAME command in the DOS manual. Paths to your source code. Just like all DOS applications, the MacHY Group's software has access to directories via "paths". The default paths are described above. If you do not wish to use the default paths to get to your COBOL source code and copybooks, you can change the paths. The names of the paths (environment variables) for the COBOL source code and copybooks are SEOCOBOL and SEOCOPY, respectively. How you're able to change paths is beyond the scope of this document. Please refer to your DOS manual (SET command). Adding new source code (after installation). There are two ways of adding new COBOL programs: add programs to an existing application identifier or create a whole new set of programs for a new application identifier. You add programs to an existing application identifier by simply copying them to the appropriate directories; but, you must run the preproces- sor again before you can parse the new programs and load them into PEO. This does not apply to copybooks. You do not have to re-run the preprocessor when you add copy books - - unless the copy books contain the ENTRY statement or SELECT ... ASSIGN TO .... statements. You add a new application identifier by (1) creating a sub directory of MACHY for the new application identifier and (2) creating three subdirectories of the ap- plication identifier: COBOL, COPY, and EXS. You use the DOS MD (make directory) command to create directories. You provide the value for application identifier. It's a name to describe the group of programs just like the one mentioned in "Installing PEO". Even if the paths to your source code and copybooks will not be defaults (i.e., they will not lead to the COBOL and COPY subdirectories of the new application identifier), you MUST create the application identifier subdirectory of MACHY and an EXS subdirectory of application identifier. And, you must run the preprocessor for the new application identifier. ASCII files only. All source code input to the preprocessor and parser must be ASCII and must have columns one through six and column seven present. The COBOL statements must be in columns eight through 72. Of course, a LF/CR can terminate the record in any column, including column one (to indicate a blank line). Basically, what this means is there can be no TAB characters. Clean compiles only, please. PEO/SEO is not designed to help find potential compile errors. It's designed to replace the need to research static code in the traditional ways. It's not intended to replace Animate or any other execution-time debugging tools, just as doing re- search on static code has never done away with the need for run-time debugging tools. Nor, has run-time debugging done away with the need for "code walk-through". PREPARING DATA FOR PEO. Every thing has its price in order to get its benefits. PEO's price is the preprocessor and parser. The preprocessor saves you the task (often very difficult) of identifying the COBOL programs which contain the alternate entry points called by other programs; and it obtains other information about your COBOL programs that is required by the parser. The preprocessor "bundles" information about the various COBOL source files and passes the information to the parser. The parser identifies the relations and prepares data for PEO. Finally, the data are loaded into PEO. The preprocessor The preprocessor must be run at least one time for each applica- tion identifier. It will process every COBOL program and copy book in the COBOL and COPY subdirectories (or, alternate sub directories, see "Paths to your source code"). If you do not add new programs or add/change CALL, ENTRY, or FD statements, you should not have to run the preprocessor more than once for an application identifier. Run the preprocessor by changing to the MACHY directory and typing PREPRO application-identifier where, application-identifier, is the name you provided for the set of COBOL programs at installation time. Of course, applica- tion identifier can also be any name you've added to the MACHY directory since installation. Main Programs The preprocessor identifies all the main programs in the applica- tion identifier directory. The preprocessor identifies a "main" program by finding a program which no other program CALLs, either directly or by alternate entry points. A main program should have no alternate entry points (except, DLITCBL) and it must have a PROGRAM-ID name which matches the source file name. If the pre- processor cannot identify any main programs, no files are produced for the parser. The SEOPREP.SEO file This file lists the things encountered by the preprocessor. The things important to the user are limited to identifying missing components; e.g., copybooks. The file is in the application identifier sub directory of MACHY. The parser The parser must be run every time you wish to add a program to PEO, or every time you make major changes to a program which require all the new relations in the changed program to be re- identified. Run the parser by entering seoexp00 applid program-id Applid is the same as described in "The preprocessor". Program id is the file name of the COBOL program. You do not have to include the .CBL extension. If you omit the program name the parser will parse all programs in the COBOL source code direc- tory. If you include more than one program name, the parser will ask you to input a one to eight byte name; all the programs will be parsed together and you will have to use the name to load the parser files into PEO. The parser is executed from the MACHY directory. The progid.seo file If the parser detects any things it cannot handle it writes messages to a file identified by the program name and .seo extension. You should check this file for missing subprograms or copybooks, unknown data element names, or anything which might affect the ability to analyze the program. If you parsed a group of programs together, the file name will be the name you provided to the parser plus the .seo extension. The files are in the EXS sub directory of the application identifier. Loading output from the parser into PEO. When PEO is invoked you will be asked to choose to load a program or select a program already in PEO to view. If you choose to load a program and the program already exists in PEO, you will be asked to permit PEO to overlay the old program. Once the program is loaded, you will see the orig- inal screen, The PEO (Program Entity Organizer) SCREEN (Figure 1). You can select the program you wish to view. You invoke PEO by entering PEO on the DOS command line. You must, however, first change to the EXS sub directory of the application identifier. The peo.exe file can reside in any directory; but, when it's in the EXS sub directory it can use default paths to load data files from the parser. PEO works with Microsoft Windows. It's recommended you add PEO to Windows. USING THE PEO SCREENS Note: the illustrations of the PEO screens and the PEO demo referenced beloware not included with the shareware "test drive" version. No training required. Anyone can use the PEO screens with just a few minutes of practice. It's best to have an actual application; i.e., don't expect to peruse code for the sole purpose of seeing how PEO works. The amount of information provided by PEO can overwhelm the senses. But, if you start with a specific task in mind you'll quickly get up to speed. That's why we have included a speed learning exercise with this manual. Please see, The PEO Demo. (Not included with this package.) Here is some information, followed by some guidelines, which will help you learn even faster. First, here is a brief description of the PEO screens. The PEO Screens. The first screen you see after peo.exe is executed is the PEO (Program Entity Organizer) SCREEN (Figure 1). This screen has a little pop-up window in the right side. The window gives you the option of loading a new program (including overlaying an existing program) or you can elect to view a program already loaded. Use the arrow keys and Enter to select. The PEO Data Element Selection Screen The next screen is the PEO DATA ELEMENT SELECTION SCREEN (Figure 2). This screen is used to select any element (entity) in the program. Elements include data element names, procedure names, program names, subprogram names, entry points, copy books, etc. You must do one of three things: 1. type in the whole name, 2. type in a partial name and press F-7, or 3. press F-7 If you pressed F-7, you will see a pop-up window containing a list of element names. Use the arrow and page keys and press enter to make a selection. The pop-up window disappears and the selected name remains on the screen. Now you must do one of two things: 1. press F-5 to see how other entities in the program relate to the selected element or 2. press F-6 to see the source code. If you pressed F-6, you will see the PEO SOURCE DISPLAY SCREEN (Figure 3). If you pressed F-5, the next screen you see is the PEO ELEMENT DISPLAY SCREEN (Figure 4). The PEO SOURCE DISPLAY SCREEN. If you pressed F-6, the PEO SOURCE DISPLAY SCREEN (Figure 3), you have two options: 1. use the arrow, page-up, and page-down keys to view the source code or 2. press Esc or Enter to return to the prior screen, the PEO DATA ELEMENT SELECTION SCREEN (Figure 2). The PEO Element Display Screen If you pressed F-5, you have the PEO ELEMENT DISPLAY SCREEN Figure 4). The PEO ELEMENT DISPLAY SCREEN (Figure 4) is the main working screen to view and trace relations. This screen is also referred to as the element relations screen. This is the main working screen. It is what PEO is about. The screen has three main parts: 1. the target element, 2. elements that affect the target, and 3. elements affected by the target. The target element and affected elements The target element is the element you selected on the PEO DATA ELEMENT SELECTION SCREEN (Figure 2). The part of the screen which shows the elements that affect the target is a list of elements and the nature of their affect. The part of the screen which shows the elements affected by the target is a list of elements and the nature of the target's affect. Both pars scroll and both parts show some additional informa- tion. This is, in effect, an enhanced cross reference. This shows the target, the elements directly related to it, and the nature of the relation. Picking a target Before you can decide which new target to view, it will be likely you'll need to see the source code associated with each of the relations listed on the screen. To see the source code, use the arrow keys to select the related element and press F-6. This brings up the PEO SOURCE DISPLAY SCREEN (Figure 3). The PEO SOURCE DISPLAY SCREEN (Figure 3) gives you the same two options described above: 1. use the arrow, page-up, and page-down keys to view the source code or 2. press Esc or Enter to return to the prior screen, the PEO ELEMENT DIS PLAY SCREEN (Figure 4). Linking CALL and ENTRY PT relations. There are several relations for the CALL and ENTRY verbs. The relations involve data passed between modules and the passing of control to a subprogram. The relations for data elements are ALIAS, GRPPARM, PRM:CALL, and ARG:ENTR. Please refer to the discussion of relations for a description of these types of relations. The purpose of this discussion is to describe the usage of relations when following the passage of control from one program to another. These relations are: CALL:PRC, CALL, and ENTRY PT. The CALL:PRC relations indicates there is a CALL verb in a named procedure, e.g., a paragraph. You get this type of relation on the PEO ELEMENT DISPLAY SCREEN (Figure 4) when a procedure is the target and the procedure contains a CALL verb. To get detailed information about the call, place the cursor on the line containing the CALL:PRC type of relation and press enter. This makes the CALL statement the new target. The PEO ELEMENT DISPLAY SCREEN (Figure 4) for the new target will contain a detailed de- scription of the CALL; including, the ENTRY PT type of relation. But, ENTRY PT will be there only in the case of the first call to the particular entry point. Press F-6 with the cursor on the ENTRY PT type of relation to see the source code at the entry point. (Note: by "first call", we mean it is the first call encountered by the parser as it read through the program sequentially; not necessarily, the first call executed if the program were running.) When there are multiple calls to the same entry point in a program, only the first instance of the call will have the ENTRY PT type of relation. You cannot use F-6 to get to the source code at the entry point. (F-6 will show you the call to the entry point.) You must place the cursor on the CALL type of rela- tion and press Enter; the new target will be the called sub program. This is the only way you can view the called sub program's source code when there is no ENTRY PT type of relation. The PEO Multiple Element Selection Screen This screen comes in the form of a pop-up window on the PEO DATA ELEMENT SELECTION SCREEN (Figure 2). You get this when an element name is used to define more than one entity in the program. You are provided with the subprogram name and the name of the copy book (if any) to help you make a selection. CAUTIONS. Here are some important things you should know. The SEO parser and preprocessor use temporary files. These files are deleted at the end of the run. The temporary files are created in the default (working) directory, unless the default directory is overridden by an environment variable. The files in the directory used by the SEO preprocessor and parser have .cpt, .nha, .wrk, .inx, .idx, .f1, .f2, .f1s, .f2s, .sw*, .mg*, and .tmp extensions. Future versions of PEO/SEO may add to this list of temporary file extensions. ALL WORK FILES IN THE DIREC- TORY USED BY THE SEO PREPROCESSOR AND PARSER WHICH HAVE THESE EXTENSIONS WILL BE DELETED! Make sure you always run PEO/SEO in a directory which does NOT contain any of your files. ADDITIONAL INFORMATION Here are a few things you should know. In no particular order they are: PEO's target has always been mainframe COBOL programs; especially, old poorly-structured code. This, of course, happens because programs that old have been changed through the years by a variety of programmers. The developers of the preprocessor and parser did not include the capability to recognize some PC COBOL features; e.g., MicroFocus call-by-number and call-by-name features. Nor, is COBOL II nested subprograms supported. The parser is not designed for any particular release of COBOL. It attempts to avoid problems by recognizing reserved words from all releases and stops running when one of the words is used as a data element name. If one of the reserved words is used as a procedure name (such as, END-SEARCH where the paragraph name may be the exit for a para- graph containing a SEARCH verb) the parser writes a message to the program's .seo file and ignores the name. See "RESERVED WORDS". CALL is supported; but, if the CALL is to a variable name and the variable name is not identical to the CALLed program's entry point, the parser cannot recognize the subprogram. COPY ... REPLACING .... is supported; but, the source code you see on the PEO SOURCE screens does not show the effects of the changes -- even though, the changes are shown on the PEO DATA ELEMENT SELECTION (Figure 2) and PEO ELEMENT DISPLAY (Figure 4) screens. The following COBOL reserved words are recognized but are not processed by the current version of the parser: EXHIBIT, CANCEL, CLOSE, ENTER, CONTINUE, SEEK, TALLY, USE Data definitions must end with a period and space. A LF/CR may follow the period in lieu of a space. Procedures must end with a period and space. A LF/CR may follow the period in lieu of a space. TITLE. EJECT, SKIP1, SKIP2, SKIP3, REPLACE, -INC, and ++INCLUDE are ignored. TAB characters cause the parser to terminate early. The COPY directive is the only compiler directive supported. The PC COBOL SELECT ... ASSIGN TO .... options are not recognized by SEO and the name SEO picks for the DDNAME is unpredictable. Lower case letters are converted to upper case letters. The COBOL II, READ ... AT END imperative-statement NOT AT END imperative-statement results in NOT AT END being considered as data element names and they are flagged as UNKNOWN DATA ELEMENT's and written to the program's .seo file. TYPE RELATIONS CODES See TYPE column on the PEO ELEMENT DISPLAY SCREEN (Figure 4). ACCEPT ACCEPT. Indicates the data element name is related to an ACCEPT verb. The data element may be a component of a group referenced by the ACCEPT. ADD ADD. The element is a term in an ADD statement. ADDCORR ADD CORRESPONDING. The element is a member of a group referenced in an ADD ... CORR statement. ALIAS PARAMETER RELATED TO ARGUMENT. Shows the data element used in the subprogram when the TARGET is the data element in the calling program. Shows the data element used in the calling program when the TARGET is the data element in the CALLed program. ARG:ENTR ARGUMENTS RELATED TO AN ENTRY POINT. This appears on the PEO ELEMENT DISPLAY SCREEN when the target is a CALLed entry point. It provides a connection between the entry point and the arguments. CALL CALL. Indicates a call to an entry point. CALL:PRC CALL RELATED TO PROCEDURE NAME. The call to the subprogram is contained in the procedure and the procedure is the TARGET. COMPUTE COMPUTE. Indicates the data element is part of a COMPUTE statement. CONDITIN CONDITION NAME. This is the 88-level condition name and the variable name which it names. DISPLAY DISPLAY. Indicates the data element name is related to an DISPLAY verb. The data element may be a component of a group referenced by the DISPLAY. DIVIDE DIVIDE. The element is a term in a DIVIDE statement. DEPEND DEPENDING ON. Indicates the data element is used in a GO TO ... DEPENDING ON data-element-name statement. ELEM:GRP ELEMENT RELATED TO GROUP. This is the data definition for a component/group relation. It points to the data definition for the group containing the element. ENTRY PT ENTRY POINT. Indicates an entry point invoked by the corresponding CALL type. EVALUATE EVALUATE. The element is in a EVALUATE condition phrase. FALLTHRU FALL THROUGH. This indicates the procedure immediately preceding another procedure had no statements and control falls through to the second procedure. This was included as a relation because, often, a program will perform a section name. Immediately following the section name is a paragraph name. FALLTHRU makes it possible to identify the paragraph name without having to view the source code first. FLOW IN ELEMENT FLOWS INTO PROCEDURE NAME. The element is contained in the procedure (TARGET) and is not modified. FLOW OUT ELEMENT FLOWS FROM PROCEDURE NAME. The element is contained in the procedure (TARGET) and is modified by the procedure; or, in the case of a DISPLAY, WRITE, etc., the data are output from the procedure. GRPMOVE GROUP MOVE. Indicates the element is a member of a group referenced in a MOVE statement. GRPPARM GROUP PARAMETER. Indicates the element is a member of a group which is referenced in a CALL, ENTRY, or PROCEDURE DIVISION USING statement. GRPREAD GROUP READ. Indicates the element is a member of a group referenced in a READ/RETURN statement. GRPWRITE GROUP WRITE. Indicates the element is a member of a group referenced in a WRITE/REWRITE/RELEASE statement. IF IF. Indicates the element is used in an IF statement. JCL PARM JCL PARAMETER. This appears on the screen, along with the type relation which points to the beginning of the source file's PROCEDURE DIVISION. It represents the data element names passed to the main program via MVS JCL PARM=parameters sub-element of the EXEC card. KEY KEY. The data element is used as a key for a READ direct or START statement. MULTIPLY MULTIPLY. The element is a term in a MULTIPLY statement. OPEN IN OPEN INPUT. This connects the DD name to the file in an OPEN INPUT statement. If there is an OPEN I-O there will an OPEN output relation, also. OPEN OUT OPEN OUTPUT. This connects the DD name to the file in an OPEN OUTPUT statement. If there is an OPEN I-O there will be an OPEN input relation, also. PERFORM PERFORM PROCEDURE. This points to where the PERFORM statement is coded. PERFORMP PERFORM TEXT. This points to where the PERFORMed procedure is located; i.e., this is the text of the procedure. PRM:CALL PARAMETERS RELATED TO A CALL VERB. This appears on the PEO ELEMENT DISPLAY SCREEN when the target is a CALLed entry point. It provides a connection between the CALL verb and the parameters. READ READ. Identifies the record in a READ statement. RELEASE RELEASE STATEMENT. The TARGET element is referenced in a RELEASE verb. REMAINDR REMAINDER. The data element is referenced as the remainder in a DIVIDE statement. REDEFINE REDEFINES. This indicates a redefines condition. RENAMES RENAMES. This is the renames condition. RETURN RETURN STATEMENT. The TARGET element is referenced in a SORT RETURN verb. REWRITE REWRITE STATEMENT. The TARGET is referenced in a REWRITE statement. SEARCH SEARCH. Indicates the data element is used in a SEARCH statement. SET SET. Indicates the data element is referenced in a SET statement. SORT IN SORT INPUT PROCEDURE. This points to where the SORT statement is coded. SORT INP SORT INPUT PROCEDURE. This points to where the SORT INPUT PROCEDURE is located. SORT OP SORT OUTPUT PROCEDURE. This points to where the SORT statement is coded. SORT OPP SORT OUTPUT PROCEDURE. This points to where the SORT OUTPUT PROCEDURE is located. SRCEFILE SOURCE FILE. This points to the beginning of the PROCEDURE DIVISION of the main program. STRING STRING. Indicates the data element is used in a STRING statement. SUBCORR SUBTRACT CORRESPONDING. The element is a member of a group referenced in a SUBTRACT ... CORR statement. SUBSCRPT SUBSCRIPT. Indicates the data element is used as a sugscript. SUBTRACT SUBTRACT. The element is a term in a SUBTRACT statement. UNSTRING UNSTRING. Indicates the data element is used in a STRING statement. WRITE WRITE. Identifies the record in a write statement. PERFORMANCE CONSIDERATIONS You will note the PEO screens are extremely fast, no matter how big the COBOL program is. But, the parser's performance is affected by the size of a program and contents of a program; especially, if the program contains a number of "group" MOVEs (i.e., the number of groups moved, read, written, or passed as parameters). Each element in the sending group is matched to a corresponding element in the receiving group. This requires extra time, especially in older programs where it's common to move groups frequently in and out of save areas and pass entire groups of elements to subprograms. There is no good solution short of turning off the group move logic; but, then there a risk of losing critical information. A RAM drive can improve the performance of the parser. Ram drives Put some of the temporary files used by the parser on a RAM drive. This is done by setting the paths to the temporary files to the RAM drive. The environment variable names for the temporary files are: SEOIDX, SEOINX, SEOINXHI, SEOMST, and SEOSORT. If you don't have enough memory to put all these files on a RAM drive, SEOIDX and SEOMST are the two most important ones. How big should the RAM drive be? As a rule of thumb, try one meg for every 10,000 lines of code in the COBOL program. You may have to estimate the size; because, the size is not the size of the main source file. The size is the total lines of code for all source files and copybooks in the entire program. The factor that dictates the storage requirements is actually the number of data elements in the program. It takes about 500 bytes per data element, mostly due to the sortwork files, SEOSORT. The two most important files are SEOIDX and SEOMST. The SEOSORT environment variable is for the sortwork files. If they default to the hard drive it just means the sort will take a little longer. A sort occurs at the end of each DATA DIVISION and at the end of each PROCEDURE DIVISION. The SEOINXHI will usually be core resident. Also, if your program contains 10 or more modules (separately compiled subprograms) you may have to specify additional directory space when you define the RAM drive. The parser creates several work files for the main program and for each subprogram. Please refer to your DOS manual for information about defining RAM drives. Output from the preprocessor and parser. The output from the preprocessor is usually quite small. There are two files which the parser uses, execprgm.prg and entrypt.eps. Both of these files, along with the seoprep.seo file, are in the application ID subdirectory of MACHY. The output from the parser is usually quite large and is written to the EXS subdirectory of the application ID. The parser creates three files for PEO to load into its data bases. The three files are: <progid>.dat, <progid>.exp, and <progid>.prc. Once PEO has loaded these data into its data bases you can delete the three files. (If you combined programs for analysis, the three files will be named after the name you provided to the parser.) The amount of storage required for these three files depend upon the size of the program(s) and the amount of group activity in the COBOL programs. E.g., one program we've worked with had over 50,000 lines of code (including subprograms) and required about 10,000,000 bytes of storage for the three files. Another program had 34,000 lines of code, but it required about 20,000,000 bytes of storage. The difference was, the second program did almost everything at the group level, MOVE's, parameters, etc. The parser attempts to relate the elements in the sending and receiving groups, meaning there were several hundred relations for each group activity. So, it's a good idea to delete the .dat, .exp, and .prc files once they've been loaded into the PEO data bases. RESERVED WORDS COBOL reserved words from the various versions of COBOL must not be used as data element names or procedure names. IV. JWY&Assoc., Inc.'s support for PEO. JAMES W. YOUNG & ASSOCIATES, INC. provides three month's mail and CompuServe support in accordance with the Association of Shareware Professionals' policy of support for registered software, applicable to JWY&Assoc, Inc.'s PEO. After that period, support can be continued by licensee paying ten (10) percent of the original registration price (ten percent of $119.00, or $11.90, annually. Customization of SEO (the parser) and PEO is available, on-site and off-site. Please contact JWY&Assoc, Inc. for more information. V. qikstart DISCLAIMER - AGREEMENT USERS OF PROGRAM ENTITY ORGANIZER (PEO) AND ITS SUPPORTING SOFTWARE, THROUGHOUT THIS DOCUMENT, REFERRED TO AS SEO, MUST ACCEPT THIS DISCLAIMER OF WARRANTY: PROGRAM ENTITY ORGANIZER (PEO) AND SEO ARE SUPPLIED AS IS. THE AUTHOR AND PUBLISHER DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THE WARRANTIES OF MERCHANTABILITY AND OF FITNESS FOR ANY PURPOSE. THE AUTHOR AND PUBLISHER ASSUME NO LIABILITY FOR DAMAGES, DIRECT OR CONSEQUENTIAL, WHICH MAY RESULT FROM THE USE OF PROGRAM ENTITY ORGANIZER (PEO) AND SEO. THE USER MUST ASSUME THE ENTIRE RISK OF USING THE PROGRAM. ANY LIABILITY OF THE AUTHOR AND PUBLISHER WILL BE LIMITED EXCLUSIVELY TO PRODUCT REPLACEMENT OR REFUND OF PURCHASE PRICE. How to install PEO. Run the install batch file by changing to the directory containing the file and type the following install x applicationID where, x is the target hard drive letter (WITHOUT THE COLON) and applicationID is a one to eight byte name you give to your set of COBOL programs. The install.bat file will create a directory called, MACHY. The install.bat file then copies the PEO files to the MACHY directory. The install.bat file creates a sub directory of MACHY by using the one to eight byte applicationID. Install.bat will create three sub directories of the application ID: COBOL, COPY, and EXS. The peo.exe file is copied to the EXS sub directory. The EXS sub directory is used by the parser to pass files to peo.exe. The COBOL and COPY sub directories are defaults for the application ID's source code. Here's what the directories look like after install.bat is run: root the c: drive | MACHY the preprocessor and parser are here | application ID the working directory for a set of COBOL | code | |_ EXS the peo.exe file resides here | |_ COBOL the default for the COBOL source files | |_ COPY the default for the copy books How to start using PEO. PEO is as easy to use as 1, 2, 3: 1. preprocess all the COBOL source code and copy books, 2. parse the program(s), and 3. load into the PEO data base, then analyze the program. Step one must be done at least one time during the "life-cycle" of PEO for a particular set of COBOL programs. Step two parses the COBOL program and prepares it for PEO. Step three, PEO, loads the COBOL program's output from the parser and interacts with the user with easy to use screens to do the analysis and documentation. How to execute the programs. From the MACHY directory: Type prepro applicationID where applicationID is the same as above. This is step one. After step one finishes, type seoexp00 applicationID programname where applicationId is the same as above and programname is the name of the COBOL source file. This is step two. Change to the \MACHY\applicationID\EXS directory and type peo Follow the instructions on the PEO screens to load the program and select the program for analysis and documentation. The PEO screens are intuitive and you'll recognize immediately how similar they are to using a compile listing for analysis. It's likely your COBOL source code is already installed in a directory; or, you do not want to put the programs and copybooks in the PEO default directory. If either is true, you must set the DOS environment variables listed below; type set SEOCOBOL=drive[path] set SEOCOPY=drive[path] where drive is the letter of the drive containing the COBOL source code and [path] is the path to the directory of the source code. The COBOL programs must have a .cbl file extension and the copy books must have a .cpy file extension. The DOS RENAME command can add/change extensions for all files in a single directory. Please refer to the DOS manual. The DETAILS.DOC file contains a deeper explanation of these procedures and a discussion of performance considerations. One final note. PEO was designed for mainframe COBOL; e.g., ANS74, ANS85, OS/VS, and most of COBOL II. It does not support many of the language extensions found in PC-based COBOL. See the file CAUTION.DOC.